// --------------------------------------------------------------------------------------------------------------------
// <copyright file="IGridBasedPathPlanner.cs" company="Microsoft Corporation">
// The MIT License (MIT)
// 
// Copyright (c) 2014, Microsoft Corporation
// 
// Permission is hereby granted, free of charge, to any person obtaining a copy
//  of this software and associated documentation files (the "Software"), to deal
//  in the Software without restriction, including without limitation the rights
//  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
//  copies of the Software, and to permit persons to whom the Software is
//  furnished to do so, subject to the following conditions:
// 
// The above copyright notice and this permission notice shall be included in
//  all copies or substantial portions of the Software.
// 
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
//  THE SOFTWARE.
// </copyright>
// --------------------------------------------------------------------------------------------------------------------
namespace Microsoft.Robotics.Navigation.Motion
{
    using System.Collections.Generic;
    using Microsoft.Robotics.Numerics;

    /// <summary>
    /// Interface for grid based path planners
    /// </summary>
    public interface IGridBasedPathPlanner
    {
        /// <summary>
        /// Initialize the planner
        /// </summary>
        /// <param name="mapWidth">Width of the map in grid cells.</param>
        /// <param name="mapHeight">Height of the map in grid cells</param>
        /// <param name="corridorBuffer">Distance from walls and obstacles considered open for straight paths.</param>
        /// <param name="skeletonThreshold">Maximum distance between origin between adjacent points along a ridge, to be considered part of the skeleton.</param>
        /// <param name="radius">Radius of the robot in grid squares</param>
        void Initialize(int mapWidth, int mapHeight, int corridorBuffer, int skeletonThreshold, int radius = 0);

        /// <summary>
        /// Returns a path for the given map, and current/goal locations.  Throws application exception when no path is possible.
        /// </summary>
        /// <param name="map">Occupancy map</param>
        /// <param name="currentLocation">Current location.</param>
        /// <param name="goalLocation">Goal location.</param>
        /// <returns>An ordered list of the points from the current location to the goal location.</returns>
        IEnumerable<Point2D<int>> GetPath(bool[] map, Point2D<int> currentLocation, Point2D<int> goalLocation);
    }
}
